3 namespace Wikimedia\Rdbms
;
5 use InvalidArgumentException
;
8 * Helper class to handle automatically marking connections as reusable (via RAII pattern)
9 * as well handling deferring the actual network connection until the handle is used
11 * @note: proxy methods are defined explicitly to avoid interface errors
15 class DBConnRef
implements IDatabase
{
16 /** @var ILoadBalancer */
18 /** @var Database|null Live connection handle */
20 /** @var array|null N-tuple of (server index, group, DatabaseDomain|string) */
29 * @param ILoadBalancer $lb Connection manager for $conn
30 * @param Database|array $conn Database handle or (server index, query groups, domain, flags)
32 public function __construct( ILoadBalancer
$lb, $conn ) {
34 if ( $conn instanceof Database
) {
35 $this->conn
= $conn; // live handle
36 } elseif ( is_array( $conn ) && count( $conn ) >= 4 && $conn[self
::FLD_DOMAIN
] !== false ) {
37 $this->params
= $conn;
39 throw new InvalidArgumentException( "Missing lazy connection arguments." );
43 function __call( $name, array $arguments ) {
44 if ( $this->conn
=== null ) {
45 list( $db, $groups, $wiki, $flags ) = $this->params
;
46 $this->conn
= $this->lb
->getConnection( $db, $groups, $wiki, $flags );
49 return $this->conn
->$name( ...$arguments );
52 public function getServerInfo() {
53 return $this->__call( __FUNCTION__
, func_get_args() );
56 public function bufferResults( $buffer = null ) {
57 return $this->__call( __FUNCTION__
, func_get_args() );
60 public function trxLevel() {
61 return $this->__call( __FUNCTION__
, func_get_args() );
64 public function trxTimestamp() {
65 return $this->__call( __FUNCTION__
, func_get_args() );
68 public function explicitTrxActive() {
69 return $this->__call( __FUNCTION__
, func_get_args() );
72 public function assertNoOpenTransactions() {
73 return $this->__call( __FUNCTION__
, func_get_args() );
76 public function tablePrefix( $prefix = null ) {
77 if ( $this->conn
=== null && $prefix === null ) {
78 $domain = DatabaseDomain
::newFromId( $this->params
[self
::FLD_DOMAIN
] );
79 // Avoid triggering a database connection
80 return $domain->getTablePrefix();
81 } elseif ( $this->conn
!== null && $prefix === null ) {
82 // This will just return the prefix
83 return $this->__call( __FUNCTION__
, func_get_args() );
85 // Disallow things that might confuse the LoadBalancer tracking
86 throw new DBUnexpectedError( $this, "Database selection is disallowed to enable reuse." );
89 public function dbSchema( $schema = null ) {
90 if ( $this->conn
=== null && $schema === null ) {
91 $domain = DatabaseDomain
::newFromId( $this->params
[self
::FLD_DOMAIN
] );
92 // Avoid triggering a database connection
93 return $domain->getSchema();
94 } elseif ( $this->conn
!== null && $schema === null ) {
95 // This will just return the schema
96 return $this->__call( __FUNCTION__
, func_get_args() );
98 // Disallow things that might confuse the LoadBalancer tracking
99 throw new DBUnexpectedError( $this, "Database selection is disallowed to enable reuse." );
102 public function getLBInfo( $name = null ) {
103 return $this->__call( __FUNCTION__
, func_get_args() );
106 public function setLBInfo( $name, $value = null ) {
107 // Disallow things that might confuse the LoadBalancer tracking
108 throw new DBUnexpectedError( $this, "Changing LB info is disallowed to enable reuse." );
111 public function setLazyMasterHandle( IDatabase
$conn ) {
112 // Disallow things that might confuse the LoadBalancer tracking
113 throw new DBUnexpectedError( $this, "Database injection is disallowed to enable reuse." );
116 public function implicitGroupby() {
117 return $this->__call( __FUNCTION__
, func_get_args() );
120 public function implicitOrderby() {
121 return $this->__call( __FUNCTION__
, func_get_args() );
124 public function lastQuery() {
125 return $this->__call( __FUNCTION__
, func_get_args() );
128 public function doneWrites() {
129 return $this->__call( __FUNCTION__
, func_get_args() );
132 public function lastDoneWrites() {
133 return $this->__call( __FUNCTION__
, func_get_args() );
136 public function writesPending() {
137 return $this->__call( __FUNCTION__
, func_get_args() );
140 public function preCommitCallbacksPending() {
141 return $this->__call( __FUNCTION__
, func_get_args() );
144 public function writesOrCallbacksPending() {
145 return $this->__call( __FUNCTION__
, func_get_args() );
148 public function pendingWriteQueryDuration( $type = self
::ESTIMATE_TOTAL
) {
149 return $this->__call( __FUNCTION__
, func_get_args() );
152 public function pendingWriteCallers() {
153 return $this->__call( __FUNCTION__
, func_get_args() );
156 public function pendingWriteRowsAffected() {
157 return $this->__call( __FUNCTION__
, func_get_args() );
160 public function isOpen() {
161 return $this->__call( __FUNCTION__
, func_get_args() );
164 public function setFlag( $flag, $remember = self
::REMEMBER_NOTHING
) {
165 return $this->__call( __FUNCTION__
, func_get_args() );
168 public function clearFlag( $flag, $remember = self
::REMEMBER_NOTHING
) {
169 return $this->__call( __FUNCTION__
, func_get_args() );
172 public function restoreFlags( $state = self
::RESTORE_PRIOR
) {
173 return $this->__call( __FUNCTION__
, func_get_args() );
176 public function getFlag( $flag ) {
177 return $this->__call( __FUNCTION__
, func_get_args() );
180 public function getProperty( $name ) {
181 return $this->__call( __FUNCTION__
, func_get_args() );
184 public function getDomainID() {
185 if ( $this->conn
=== null ) {
186 $domain = $this->params
[self
::FLD_DOMAIN
];
187 // Avoid triggering a database connection
188 return $domain instanceof DatabaseDomain ?
$domain->getId() : $domain;
191 return $this->__call( __FUNCTION__
, func_get_args() );
195 * @codeCoverageIgnore
197 public function getWikiID() {
198 return $this->getDomainID();
201 public function getType() {
202 return $this->__call( __FUNCTION__
, func_get_args() );
205 public function fetchObject( $res ) {
206 return $this->__call( __FUNCTION__
, func_get_args() );
209 public function fetchRow( $res ) {
210 return $this->__call( __FUNCTION__
, func_get_args() );
213 public function numRows( $res ) {
214 return $this->__call( __FUNCTION__
, func_get_args() );
217 public function numFields( $res ) {
218 return $this->__call( __FUNCTION__
, func_get_args() );
221 public function fieldName( $res, $n ) {
222 return $this->__call( __FUNCTION__
, func_get_args() );
225 public function insertId() {
226 return $this->__call( __FUNCTION__
, func_get_args() );
229 public function dataSeek( $res, $row ) {
230 return $this->__call( __FUNCTION__
, func_get_args() );
233 public function lastErrno() {
234 return $this->__call( __FUNCTION__
, func_get_args() );
237 public function lastError() {
238 return $this->__call( __FUNCTION__
, func_get_args() );
241 public function affectedRows() {
242 return $this->__call( __FUNCTION__
, func_get_args() );
245 public function getSoftwareLink() {
246 return $this->__call( __FUNCTION__
, func_get_args() );
249 public function getServerVersion() {
250 return $this->__call( __FUNCTION__
, func_get_args() );
253 public function close() {
254 throw new DBUnexpectedError( $this->conn
, 'Cannot close shared connection.' );
257 public function query( $sql, $fname = __METHOD__
, $tempIgnore = false ) {
258 return $this->__call( __FUNCTION__
, func_get_args() );
261 public function freeResult( $res ) {
262 return $this->__call( __FUNCTION__
, func_get_args() );
265 public function selectField(
266 $table, $var, $cond = '', $fname = __METHOD__
, $options = [], $join_conds = []
268 return $this->__call( __FUNCTION__
, func_get_args() );
271 public function selectFieldValues(
272 $table, $var, $cond = '', $fname = __METHOD__
, $options = [], $join_conds = []
274 return $this->__call( __FUNCTION__
, func_get_args() );
277 public function select(
278 $table, $vars, $conds = '', $fname = __METHOD__
,
279 $options = [], $join_conds = []
281 return $this->__call( __FUNCTION__
, func_get_args() );
284 public function selectSQLText(
285 $table, $vars, $conds = '', $fname = __METHOD__
,
286 $options = [], $join_conds = []
288 return $this->__call( __FUNCTION__
, func_get_args() );
291 public function selectRow(
292 $table, $vars, $conds, $fname = __METHOD__
,
293 $options = [], $join_conds = []
295 return $this->__call( __FUNCTION__
, func_get_args() );
298 public function estimateRowCount(
299 $table, $vars = '*', $conds = '', $fname = __METHOD__
, $options = [], $join_conds = []
301 return $this->__call( __FUNCTION__
, func_get_args() );
304 public function selectRowCount(
305 $tables, $vars = '*', $conds = '', $fname = __METHOD__
, $options = [], $join_conds = []
307 return $this->__call( __FUNCTION__
, func_get_args() );
310 public function lockForUpdate(
311 $table, $conds = '', $fname = __METHOD__
, $options = [], $join_conds = []
313 return $this->__call( __FUNCTION__
, func_get_args() );
316 public function fieldExists( $table, $field, $fname = __METHOD__
) {
317 return $this->__call( __FUNCTION__
, func_get_args() );
320 public function indexExists( $table, $index, $fname = __METHOD__
) {
321 return $this->__call( __FUNCTION__
, func_get_args() );
324 public function tableExists( $table, $fname = __METHOD__
) {
325 return $this->__call( __FUNCTION__
, func_get_args() );
328 public function insert( $table, $a, $fname = __METHOD__
, $options = [] ) {
329 return $this->__call( __FUNCTION__
, func_get_args() );
332 public function update( $table, $values, $conds, $fname = __METHOD__
, $options = [] ) {
333 return $this->__call( __FUNCTION__
, func_get_args() );
336 public function makeList( $a, $mode = self
::LIST_COMMA
) {
337 return $this->__call( __FUNCTION__
, func_get_args() );
340 public function makeWhereFrom2d( $data, $baseKey, $subKey ) {
341 return $this->__call( __FUNCTION__
, func_get_args() );
344 public function aggregateValue( $valuedata, $valuename = 'value' ) {
345 return $this->__call( __FUNCTION__
, func_get_args() );
348 public function bitNot( $field ) {
349 return $this->__call( __FUNCTION__
, func_get_args() );
352 public function bitAnd( $fieldLeft, $fieldRight ) {
353 return $this->__call( __FUNCTION__
, func_get_args() );
356 public function bitOr( $fieldLeft, $fieldRight ) {
357 return $this->__call( __FUNCTION__
, func_get_args() );
360 public function buildConcat( $stringList ) {
361 return $this->__call( __FUNCTION__
, func_get_args() );
364 public function buildGroupConcatField(
365 $delim, $table, $field, $conds = '', $join_conds = []
367 return $this->__call( __FUNCTION__
, func_get_args() );
370 public function buildSubstring( $input, $startPosition, $length = null ) {
371 return $this->__call( __FUNCTION__
, func_get_args() );
374 public function buildStringCast( $field ) {
375 return $this->__call( __FUNCTION__
, func_get_args() );
378 public function buildIntegerCast( $field ) {
379 return $this->__call( __FUNCTION__
, func_get_args() );
382 public function buildSelectSubquery(
383 $table, $vars, $conds = '', $fname = __METHOD__
,
384 $options = [], $join_conds = []
386 return $this->__call( __FUNCTION__
, func_get_args() );
389 public function databasesAreIndependent() {
390 return $this->__call( __FUNCTION__
, func_get_args() );
393 public function selectDB( $db ) {
394 // Disallow things that might confuse the LoadBalancer tracking
395 throw new DBUnexpectedError( $this, "Database selection is disallowed to enable reuse." );
398 public function selectDomain( $domain ) {
399 // Disallow things that might confuse the LoadBalancer tracking
400 throw new DBUnexpectedError( $this, "Database selection is disallowed to enable reuse." );
403 public function getDBname() {
404 if ( $this->conn
=== null ) {
405 $domain = DatabaseDomain
::newFromId( $this->params
[self
::FLD_DOMAIN
] );
406 // Avoid triggering a database connection
407 return $domain->getDatabase();
410 return $this->__call( __FUNCTION__
, func_get_args() );
413 public function getServer() {
414 return $this->__call( __FUNCTION__
, func_get_args() );
417 public function addQuotes( $s ) {
418 return $this->__call( __FUNCTION__
, func_get_args() );
421 public function addIdentifierQuotes( $s ) {
422 return $this->__call( __FUNCTION__
, func_get_args() );
425 public function buildLike() {
426 return $this->__call( __FUNCTION__
, func_get_args() );
429 public function anyChar() {
430 return $this->__call( __FUNCTION__
, func_get_args() );
433 public function anyString() {
434 return $this->__call( __FUNCTION__
, func_get_args() );
437 public function nextSequenceValue( $seqName ) {
438 return $this->__call( __FUNCTION__
, func_get_args() );
441 public function replace( $table, $uniqueIndexes, $rows, $fname = __METHOD__
) {
442 return $this->__call( __FUNCTION__
, func_get_args() );
445 public function upsert(
446 $table, array $rows, $uniqueIndexes, array $set, $fname = __METHOD__
448 return $this->__call( __FUNCTION__
, func_get_args() );
451 public function deleteJoin(
452 $delTable, $joinTable, $delVar, $joinVar, $conds, $fname = __METHOD__
454 return $this->__call( __FUNCTION__
, func_get_args() );
457 public function delete( $table, $conds, $fname = __METHOD__
) {
458 return $this->__call( __FUNCTION__
, func_get_args() );
461 public function insertSelect(
462 $destTable, $srcTable, $varMap, $conds,
463 $fname = __METHOD__
, $insertOptions = [], $selectOptions = [], $selectJoinConds = []
465 return $this->__call( __FUNCTION__
, func_get_args() );
468 public function unionSupportsOrderAndLimit() {
469 return $this->__call( __FUNCTION__
, func_get_args() );
472 public function unionQueries( $sqls, $all ) {
473 return $this->__call( __FUNCTION__
, func_get_args() );
476 public function unionConditionPermutations(
477 $table, $vars, array $permute_conds, $extra_conds = '', $fname = __METHOD__
,
478 $options = [], $join_conds = []
480 return $this->__call( __FUNCTION__
, func_get_args() );
483 public function conditional( $cond, $trueVal, $falseVal ) {
484 return $this->__call( __FUNCTION__
, func_get_args() );
487 public function strreplace( $orig, $old, $new ) {
488 return $this->__call( __FUNCTION__
, func_get_args() );
491 public function getServerUptime() {
492 return $this->__call( __FUNCTION__
, func_get_args() );
495 public function wasDeadlock() {
496 return $this->__call( __FUNCTION__
, func_get_args() );
499 public function wasLockTimeout() {
500 return $this->__call( __FUNCTION__
, func_get_args() );
503 public function wasConnectionLoss() {
504 return $this->__call( __FUNCTION__
, func_get_args() );
507 public function wasReadOnlyError() {
508 return $this->__call( __FUNCTION__
, func_get_args() );
511 public function wasErrorReissuable() {
512 return $this->__call( __FUNCTION__
, func_get_args() );
515 public function masterPosWait( DBMasterPos
$pos, $timeout ) {
516 return $this->__call( __FUNCTION__
, func_get_args() );
519 public function getReplicaPos() {
520 return $this->__call( __FUNCTION__
, func_get_args() );
523 public function getMasterPos() {
524 return $this->__call( __FUNCTION__
, func_get_args() );
527 public function serverIsReadOnly() {
528 return $this->__call( __FUNCTION__
, func_get_args() );
531 public function onTransactionResolution( callable
$callback, $fname = __METHOD__
) {
532 return $this->__call( __FUNCTION__
, func_get_args() );
535 public function onTransactionCommitOrIdle( callable
$callback, $fname = __METHOD__
) {
536 return $this->__call( __FUNCTION__
, func_get_args() );
539 public function onTransactionIdle( callable
$callback, $fname = __METHOD__
) {
540 return $this->__call( __FUNCTION__
, func_get_args() );
543 public function onTransactionPreCommitOrIdle( callable
$callback, $fname = __METHOD__
) {
544 return $this->__call( __FUNCTION__
, func_get_args() );
547 public function setTransactionListener( $name, callable
$callback = null ) {
548 return $this->__call( __FUNCTION__
, func_get_args() );
551 public function startAtomic(
552 $fname = __METHOD__
, $cancelable = IDatabase
::ATOMIC_NOT_CANCELABLE
554 return $this->__call( __FUNCTION__
, func_get_args() );
557 public function endAtomic( $fname = __METHOD__
) {
558 return $this->__call( __FUNCTION__
, func_get_args() );
561 public function cancelAtomic( $fname = __METHOD__
, AtomicSectionIdentifier
$sectionId = null ) {
562 return $this->__call( __FUNCTION__
, func_get_args() );
565 public function doAtomicSection(
566 $fname, callable
$callback, $cancelable = self
::ATOMIC_NOT_CANCELABLE
568 return $this->__call( __FUNCTION__
, func_get_args() );
571 public function begin( $fname = __METHOD__
, $mode = IDatabase
::TRANSACTION_EXPLICIT
) {
572 return $this->__call( __FUNCTION__
, func_get_args() );
575 public function commit( $fname = __METHOD__
, $flush = '' ) {
576 return $this->__call( __FUNCTION__
, func_get_args() );
579 public function rollback( $fname = __METHOD__
, $flush = '' ) {
580 return $this->__call( __FUNCTION__
, func_get_args() );
583 public function flushSnapshot( $fname = __METHOD__
) {
584 return $this->__call( __FUNCTION__
, func_get_args() );
587 public function timestamp( $ts = 0 ) {
588 return $this->__call( __FUNCTION__
, func_get_args() );
591 public function timestampOrNull( $ts = null ) {
592 return $this->__call( __FUNCTION__
, func_get_args() );
595 public function ping( &$rtt = null ) {
596 return func_num_args()
597 ?
$this->__call( __FUNCTION__
, [ &$rtt ] )
598 : $this->__call( __FUNCTION__
, [] ); // method cares about null vs missing
601 public function getLag() {
602 return $this->__call( __FUNCTION__
, func_get_args() );
605 public function getSessionLagStatus() {
606 return $this->__call( __FUNCTION__
, func_get_args() );
609 public function maxListLen() {
610 return $this->__call( __FUNCTION__
, func_get_args() );
613 public function encodeBlob( $b ) {
614 return $this->__call( __FUNCTION__
, func_get_args() );
617 public function decodeBlob( $b ) {
618 return $this->__call( __FUNCTION__
, func_get_args() );
621 public function setSessionOptions( array $options ) {
622 return $this->__call( __FUNCTION__
, func_get_args() );
625 public function setSchemaVars( $vars ) {
626 return $this->__call( __FUNCTION__
, func_get_args() );
629 public function lockIsFree( $lockName, $method ) {
630 return $this->__call( __FUNCTION__
, func_get_args() );
633 public function lock( $lockName, $method, $timeout = 5 ) {
634 return $this->__call( __FUNCTION__
, func_get_args() );
637 public function unlock( $lockName, $method ) {
638 return $this->__call( __FUNCTION__
, func_get_args() );
641 public function getScopedLockAndFlush( $lockKey, $fname, $timeout ) {
642 return $this->__call( __FUNCTION__
, func_get_args() );
645 public function namedLocksEnqueue() {
646 return $this->__call( __FUNCTION__
, func_get_args() );
649 public function getInfinity() {
650 return $this->__call( __FUNCTION__
, func_get_args() );
653 public function encodeExpiry( $expiry ) {
654 return $this->__call( __FUNCTION__
, func_get_args() );
657 public function decodeExpiry( $expiry, $format = TS_MW
) {
658 return $this->__call( __FUNCTION__
, func_get_args() );
661 public function setBigSelects( $value = true ) {
662 return $this->__call( __FUNCTION__
, func_get_args() );
665 public function isReadOnly() {
666 return $this->__call( __FUNCTION__
, func_get_args() );
669 public function setTableAliases( array $aliases ) {
670 return $this->__call( __FUNCTION__
, func_get_args() );
673 public function setIndexAliases( array $aliases ) {
674 return $this->__call( __FUNCTION__
, func_get_args() );
678 * Clean up the connection when out of scope
680 function __destruct() {
682 $this->lb
->reuseConnection( $this->conn
);
689 * @deprecated since 1.29
691 class_alias( DBConnRef
::class, 'DBConnRef' );